home *** CD-ROM | disk | FTP | other *** search
/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / catn / grab.n < prev    next >
Text File  |  1994-09-20  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4. grab(n)                    Tk Commands
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NAME
  11.      grab - Confine pointer and keyboard events to a window  sub-
  12.      tree
  13.  
  14. SYNOPSIS
  15.      grab ?-global? _w_i_n_d_o_w
  16.      grab _o_p_t_i_o_n ?arg arg ...?                                     |
  17. _________________________________________________________________
  18.  
  19.  
  20. DESCRIPTION
  21.      This command implements simple pointer  and  keyboard  grabs
  22.      for  Tk.   Tk's grabs are different than the grabs described
  23.      in the Xlib documentation.  When a grab is set for a partic-
  24.      ular  window,  Tk  restricts  all pointer events to the grab
  25.      window and its descendants in Tk's window hierarchy.   When-
  26.      ever  the  pointer  is within the grab window's subtree, the
  27.      pointer will behave exactly the same as if there had been no
  28.      grab  at  all  and all events will be reported in the normal
  29.      fashion.  When the pointer is outside _w_i_n_d_o_w's tree,  button
  30.      presses and releases and mouse motion events are reported to
  31.      _w_i_n_d_o_w, and window entry and window exit events are ignored.
  32.      The  grab  subtree ``owns'' the pointer: windows outside the
  33.      grab subtree will be visible on the screen but they will  be
  34.      insensitive until the grab is released.  The tree of windows
  35.      underneath the grab window can include top-level windows, in
  36.      which  case all of those top-level windows and their descen-
  37.      dants will continue to receive mouse events during the grab.
  38.  
  39.      Two forms of grabs are possible:  local and global.  A local
  40.      grab  affects only the grabbing application:  events will be
  41.      reported to other applications as  if  the  grab  had  never
  42.      occurred.   Grabs are local by default.  A global grab locks
  43.      out all applications on the screen, so that only  the  given
  44.      subtree  of  the  grabbing  application will be sensitive to
  45.      pointer events (mouse button presses, mouse button releases,
  46.      pointer  motions, window entries, and window exits).  During
  47.      global grabs the window manager  will  not  receive  pointer
  48.      events either.
  49.  
  50.      During local grabs, keyboard events  (key  presses  and  key
  51.      releases)  are  delivered as usual:  the window manager con-
  52.      trols which application receives  keyboard  events,  and  if
  53.      they are sent to any window in the grabbing application then
  54.      they are redirected to the focus window.   During  a  global
  55.      grab  Tk  grabs the keyboard so that all keyboard events are
  56.      always sent to the grabbing application.  The focus  command
  57.      is  still  used to determine which window in the application
  58.      receives the keyboard events.  The keyboard grab is released
  59.      when the grab is released.
  60.  
  61.  
  62.  
  63. Tk                                                              1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. grab(n)                    Tk Commands
  71.  
  72.  
  73.  
  74.      Grabs apply to particular displays.  If an  application  has
  75.      windows  on  multiple  displays  then  it  can  establish  a
  76.      separate grab on each display.  The  grab  on  a  particular
  77.      display  affects  only  the  windows on that display.  It is
  78.      possible for different applications on a single  display  to
  79.      have  simultaneous local grabs, but only one application can
  80.      have a global grab on a given display at once.
  81.  
  82.      The grab command can take any of the following forms:
  83.  
  84.      grab ?-global? _w_i_n_d_o_w
  85.           Same as grab set, described below.                       |
  86.  
  87.      grab current ?_w_i_n_d_o_w?                                              ||
  88.           If _w_i_n_d_o_w is specified, returns the name of the current  |
  89.           grab window in this application for  _w_i_n_d_o_w's  display,  |
  90.           or an empty string if there is no such window.  If _w_i_n_-  |
  91.           _d_o_w is omitted, the command returns a list  whose  ele-  |
  92.           ments  are  all of the windows grabbed by this applica-  |
  93.           tion for all displays, or an empty string if the appli-  |
  94.           cation has no grabs.                                     |
  95.  
  96.      grab release _w_i_n_d_o_w                                                ||
  97.           Releases  the grab on _w_i_n_d_o_w if there is one, otherwise  |
  98.           does nothing.  Returns an empty string.                  |
  99.  
  100.      grab set ?-global? _w_i_n_d_o_w                                          ||
  101.           Sets  a  grab  on _w_i_n_d_o_w.  If -global is specified then  |
  102.           the grab is global, otherwise it is local.  If  a  grab  |
  103.           was  already in effect for this application on _w_i_n_d_o_w's  |
  104.           display then it is automatically released.  If there is  |
  105.           already   a   grab  on  _w_i_n_d_o_w  and  it  has  the  same  |
  106.           global/local form as the requested grab, then the  com-  |
  107.           mand does nothing.  Returns an empty string.             |
  108.  
  109.      grab status _w_i_n_d_o_w                                                 ||
  110.           Returns  none  if  no  grab is currently set on _w_i_n_d_o_w,  |
  111.           local if a local grab is set on _w_i_n_d_o_w, and global if a  |
  112.           global grab is set.
  113.  
  114.  
  115. BUGS
  116.      It took an incredibly complex and  gross  implementation  to
  117.      produce  the  simple grab effect described above.  Given the
  118.      current implementation, it isn't safe  for  applications  to
  119.      use  the  Xlib  grab facilities at all except through the Tk
  120.      grab procedures.  If applications try to manipulate X's grab
  121.      mechanisms directly, things will probably break.
  122.  
  123.      If a single process is managing several different Tk  appli-  |
  124.      cations,  only  one  of  those applications can have a local  |
  125.      grab for  a  given  display  at  any  given  time.   If  the  |
  126.  
  127.  
  128.  
  129. Tk                                                              2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. grab(n)                    Tk Commands
  137.  
  138.  
  139.  
  140.      applications  are  in  different processes, this restriction  |
  141.      doesn't exist.
  142.  
  143.  
  144. KEYWORDS
  145.      grab, keyboard events, pointer events, window
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Tk                                                              3
  196.  
  197.  
  198.  
  199.